\chapter{快速上手}
\label{ch:getting-started}

本章展示如何从零开始完成一次 C\# 项目的转换：准备样例代码、运行转换器、验证输出 C++。

\section{示例工程结构}

假设 C\# 项目结构如下：

\begin{lstlisting}[style=bash]
MyGame/
|-- Models/
|   `-- Player.cs
|-- Services/
|   `-- PlayerService.cs
|-- Program.cs
`-- MyGame.csproj
\end{lstlisting}

\section{准备 Python 环境}

\begin{enumerate}
    \item 创建虚拟环境：
    \begin{lstlisting}[style=bash]
python -m venv .venv
source .venv/bin/activate  # Windows 下执行 .venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install cpp-orchestrator
    \end{lstlisting}
    \item 安装完成后执行 `cpp-orchestrator --help` 确认可用。
\end{enumerate}

\section{运行转换器}

在项目根目录执行：

\begin{lstlisting}[style=bash]
cpp-orchestrator convert \
    --project MyGame.csproj \
    --output ./generated-cpp \
    --namespace-root my_game
\end{lstlisting}

参数说明：

\begin{itemize}[leftmargin=*]
    \item \texttt{--project}：指定待转换的 csproj 文件
    \item \texttt{--output}：输出目录，默认会创建缺省结构
    \item \texttt{--namespace-root}：将 C\# 根命名空间转换为指定的 snake\_case 前缀
\end{itemize}

转换完成后会生成如下目录：

\begin{lstlisting}[style=bash]
generated-cpp/
|-- include/
|   |-- my_game/models/player.hpp
|   `-- my_game/services/player_service.hpp
`-- src/
    |-- my_game/models/player.cpp
    `-- my_game/services/player_service.cpp
\end{lstlisting}

\section{编译生成的 C++}

示例 CMakeLists.txt：

\begin{lstlisting}[style=cpp]
cmake_minimum_required(VERSION 3.21)
project(MyGameCpp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
add_library(my_game STATIC
    src/my_game/models/player.cpp
    src/my_game/services/player_service.cpp
)
target_include_directories(my_game PUBLIC include)
\end{lstlisting}

随后执行：

\begin{lstlisting}[style=bash]
cmake -B build -S .
cmake --build build
\end{lstlisting}

若编译无误，即代表转换流程成功。

\section{常用命令}

\begin{itemize}[leftmargin=*]
    \item \texttt{cpp-orchestrator convert}：执行单次转换
    \item \texttt{cpp-orchestrator clean}：清除缓存及生成文件
    \item \texttt{cpp-orchestrator doctor}：诊断缺失依赖
    \item \texttt{cpp-orchestrator report}：生成转换摘要与统计
\end{itemize}

\section{下一步}

完成基础体验后，建议阅读第 \ref{ch:usage-guide} 章了解配置项、第 \ref{ch:examples} 章查看高级示例。
